Aminet 1 (Walnut Creek)/Aminet - June 1993 [Walnut Creek].iso/aminet/comm/misc/xprzedzap090.lzh/README.RWM

Text File | 1992-11-30 | 10KB | 219 lines

  This is the only partly documented version of xprzedzap for use with
the new beta's of Welmat.  When Welmat itself is close to an official
release, I will be separately releasing all the XPR's that are written
as part of the project as well.  At this moment there is xprzedzap
(For ZedZip/ZedZap fidonet sessions), xprfts.library (For FTS-1, DietIFNA
and soon SeaLink  transfers) and xprclock.library (For calling an atom
clock time base to set your Amiga's clock).  Work on a few different
bi-directional transfer ideas has started, but no finished library yet
exists.

  This archive is a derivative of the work that Yves did to produce the
origional xprzedzap.library that he sent me.  I have fixed a few fidonet
transfer related issues that would not affect the library in a BBS/Term
environment.  I have also started to add some of the possible extensions
that might be added to the XPR interface (Those interested should check
out the function updstatus() in utils.c).  It should be noted that
the method described by Yves relating to the numbers in the
xpru_msg field are not (and will not) be used in Welmat.  These
fields will likely be reverted back to normal text at some later
date.

  I will be attempting to keep the latest versions of the various XPR
libraries up for fidonet file request on  1:163/109 at 2400bps, and
on 1:163/139 at 14400bps.  If you wish to help work on these libraries, please
let me know ahead of time so that I can make the latest available for
request.  If you do any changes, please send me a diff of your
changes so that I can make these available to everyone.  I am very
easy to get ahold of.

Thanks to Skip Watson ([e-mail]) who has offered to
host a mailing list to further the development of the XPR specification,
we have now started discussions on the future directions that XPR can
take.  I strongly encourage any authors interested in writing
hosts or protocols, whether freely available, shareware or commercial
to please join us.


For joining the list:

[e-mail]    with "subscribe user@site" as the body

For posts to the list:

[e-mail]

************************************************************************

From: [e-mail] (John Bickers)
Date: Mon, 23 Nov 92 08:17:38 PST
To: [e-mail]
Subject: A FAQ.

    Here's the text of the FAQ as it stands now. If you have something
    to say about it, please do so. It would also be nice to see more
    people on the list say whether they support, disagree with, or are
    indifferent to, the various issues.

    ------------------------------ 8< ------------------------------


    XPR Science Monitor                                       22.11.92


    Note that "host" refers to the application using an XPR library,
    2.0 is the current version of the XPR specification, and 3.0 is
    the future version the XPR mailing list was created to discuss.


**> UNSRESOLVED ISSUES

    1.  How to pass host data (eg, a4 or an XPR_IO pointer) to a
        callback routine.

    There are basically two ideas, referred to below as A and B. A is
    to have each top level XPR library routine accept an extra 32-bit
    parameter, which it passes on to each callback routine. B is to
    add a field to the XPR_IO structure specifically for host data,
    then have the library pass a pointer to the XPR_IO structure as an
    extra parameter to each callback routine.

    2.  How to extend the specification to allow for the passing of
        these extra values.

    WRT A, the top level XPR library routines can easily be expanded
    to take an extra parameter. Older hosts that call the new routines
    will simply pass a random value through. Because their older
    callbacks won't make use of this value anyway, it doesn't matter.

    WRT B, the XPR_IO structure can be extended by placing a magic
    cookie value in a new field so a 3.0 library can tell that it has
    been passed a 3.0 XPR_IO structure. Then the host field can be
    added somewhere after the cookie. An older library will simply
    ignore the extra fields, and an older host will not create the
    cookie.

    3.  How should the callback extension work, to cater for new
        callbacks that know about the extra parameter?

    The proposed solution is to use the callback extensions mechanism
    in the 2.0 spec. to add a new callback called xpr_updateio(),
    which must be called by a 3.0 XPR library during XPRSetup(). The
    existence of this field tells the library that the host is 3.0
    aware. If XPRSetup() completes and this callback routine was
    called, then the host knows the library is 3.0 aware.

    The proposed function for this routine is to change the callback
    slots in the XPR_IO routine to point to routines that expect the
    extra parameter passed by the 3.0 spec. The host would first set
    the XPR_IO up to point to 2.0 routines, then xpr_updateio() would
    change the callback slots to point to 3.0 routines.

    4.  How can a transfer involving multiple files indicate a success
        or failure status for each file in the batch?

    The proposed solution is that xpr_update() be used for each file
    with an xpru_updatemask of XPRU_FILENAME|XPRU_STATUS, and the
    success or failure status (XPRU_SUCCESS or XPRU_FAILURE) in
    xpru_status.

    5.  Should the XPR structures contain cookies, so pointers to them
        can be identified or verified?

    Current thinking is that if cookies are used, it should not be
    necessary to check them.

    6.  Is there a problem writing a bi-directional transfer protocol
        as an XPR library?

    Currently xpr_update() is designed to show the progress of one
    file being transferred.

    7.  Should XPR libraries be requested not to fracture the stack
        before calling a callback routine?

    The reason for this is that it means the stack trick in 1d below
    can be used with less risk. Arguments against are that it should
    not be necessary for a host to implement solution 1d anyway, that
    it may not be reliable, and that the stack is just a push/pop
    mechanism that should not be relied upon across function calls.
    Arguments for are that it can be necessary under the 2.0 spec. to
    do this sort of thing, and that the host should be able to expect
    the stack to conform to that allocated by the OS for the host's
    task.


**> POSSIBLE SOLUTIONS TO SOME PROBLEMS

    1.  How to get a handle on host information within a callback
        routine, under the 2.0 spec.

    1a  If only one handle is required per task, maintain a list of
        handles paired with task addresses. The callback routine can
        then use FindTask() and scan this list for a matching entry.
        You need access to your data segment (a4) to be able to get at
        this list.

    1b  If only one handle is required per task, use tc_Userdata, a
        field in the Exec task structure. The callback routine can
        then use FindTask(NULL)->tc_Userdata. This is very useful when
        the data segment (a4) is not available, for example when
        writing residentable programs.

    1c  If only one handle is required per data segment (a4), and this
        data segment is available, simply use a global variable.

    1d  A somewhat risky solution, if a4 and tc_Userdata are not
        available, is to push a magic cookie and the handle onto the
        stack before calling an XPR library routine. Then the callback
        routine can search back up the stack for the cookie, and thus
        locate the handle. This won't work if the XPR library
        fractures the stack before calling the callback routine, a
        feature that some compilers support.

    2.  How can an a host tell whether individual files in a batch
        file transfer were transmitted successfully, under the 2.0
        spec?

    2a  Assumptions can be made in the xpr_open() callback routine
        that the previous file was successful etc. Information from
        other callback routines can be combined with this to add
        more depth to the result. For example, if xpr_open() is
        called and the last xpr_update() on the previous file did not
        show xpru_filesize and xpru_bytes as being equal, then one
        could assume that the previous file failed. All this is very
        dubious.


**> AGREED SOLUTIONS

    The more people add their support to the issues in "UNRESOLVED
    ISSUES", the quicker they'll be resolved and be listed here.


**> AGREED MODIFICATIONS TO DOCUMENTATION

    1.  XPR libraries must not modify tc_Userdata. That should be left
        to the host level. Amongst other considerations, using this
        field would break VLT.
    ------------------------------ 8< ------------------------------

--
*** John Bickers, TAP.                   [e-mail] ***
***    "Radioactivity - It's in the air, for you and me" - Kraftwerk    ***

************************************************************************

  As well as the above, talk of asynchronous I/O, speed optimizations,
methods to set and read file timestamps, etc are being
discussed.  A log of the messages is being kept, so old messages
can be received if the desire exists.


 Russell McOrmond, Ottawa Ontario, Canada
 Freenet: [e-mail] (Faster)
 Home: [e-mail]
 FidoNet 1:163/109        Current WELMAT
 Welmat Help 1:1/139    'keeper of sources'.